home *** CD-ROM | disk | FTP | other *** search
/ PC World Interactive 7 / PC World Interactive 7.iso / pcgames / EMERGY / BC5 / EXAMPLES / OWL / CLASSES / TOOLTIP / readme.txt
Text File  |  1997-03-25  |  4KB  |  124 lines
  1. ObjectWindows 
  2. Copyright (c) 1996 Borland International
  3.  
  4. Title: TOOLTIP Example
  5.  
  6. Keywords: TTooltip;Common control
  7.  
  8. TTooltip, An Introduction
  9. =========================
  10. The TTooltip class encapsulates a tooltip control - a small
  11. pop-up window that displays a single line of descriptive text
  12. giving the purpose of tools in an application. The tools is
  13. either a window, such as a child window or control, or an
  14. application-defined rectangular area within a window's client
  15. area. The tooltip control appears only when the user puts the
  16. cursor on a tool and leaves it there for approximately one-half
  17. second. The tooltip control appears near the cursor and
  18. disappears when the user clicks a mouse button or move the
  19. cursor off the tool.
  20.  
  21.  
  22. Creating a TTooltip Object
  23. ==========================
  24. The TTooltip class offers two constructor: one for creating a
  25. brand new tooltip control and one for aliasing an existing
  26. control. The following code fragment illustrates how to create a
  27. tooltip control.
  28.  
  29.     void TMyWindow::SetupWindow()
  30.     {
  31.         TWindow::SetupWindow();
  32.  
  33.         tooltip = new TTooltip(this);
  34.         tooltip->Create();
  35.     }
  36.         
  37.  
  38. Specifying Tools to the tooltip Control
  39. ======================================= 
  40. Once you created a tooltip, you must specify the tools for which
  41. the control must display a descriptive message. To add a new
  42. tool you must first fill a TToolInfo which describes the tool.
  43. Each tool must have a integer which uniquely identifies that
  44. tool.  For example, the following code designates a rectangular
  45. area of a window as a tool.
  46.  
  47.     void
  48.     TMyWindow::AddTopLeftTool()
  49.     {
  50.         uint toolId = ID_TOPLEFT_TOOL;      // Tool ID
  51.         TRect rect(0, 0, 20, 20);           // Tool Rectangle
  52.         TToolInfo ti(this, rect, ID_TOPLEFT_TOOL);
  53.         tooltip->AddTool(ti);
  54.     }
  55.  
  56.  
  57. Providing the Tooltip Text 
  58. ========================== 
  59. When adding a tool you may provide the text to be used when
  60. describing the tool as the last parameter to the constructor of
  61. the TToolInfo structure. For example,
  62.  
  63.         static TToolInfo ti(this, rect, ID_TOPLEFT_TOOL, "Top Left");
  64.         tooltip->AddTool(ti);
  65.  
  66. However, you may opt to provide the text on demand. This allows
  67. you to customize the message display to the user. The
  68. EV_TTN_NEEDTEXT macro allow you to specify a member function
  69. which can provide the text at runtime. The following code
  70. snippet illustrates:
  71.   
  72.     class TMyWindow : public TWindow {
  73.         //
  74.         // Additional definition ommitted for clarity
  75.         //
  76.         protected:
  77.             void    HandleTooltipText(TTooltipText& tiTxt);
  78.     };
  79.  
  80.     DEFINE_RESPONSE_TABLE1(TMyWindow, TWindow)
  81.         EV_TTN_NEEDTEXT(ID_TOPLEFT_TOOL, HandleTooltipText),
  82.     END_RESPONSE_TABLE;
  83.  
  84.  
  85.     void
  86.     TMyWindow::HandleTooltipText(TTooltipText& tiTxt)
  87.     {
  88.         tiTxt.CopyText("Top Left square");
  89.     }
  90.  
  91.  
  92. Additional Information
  93. ======================
  94. 1. The notification handler of the ObjectWindows TDecoratedFrame
  95. class enhances the mechanism for specifying the tooltip text by
  96. sending a 'TTooltipEnabler' up the command chain. This allows
  97. the 'context' window to provide the text even if it did not
  98. setup the tool. For example, a grid control in focus can
  99. customize the cut, paste and copy tools to specify the data type
  100. being manipulated. ['copy cell' instead of just 'copy'].
  101.  
  102. 2. The EvCommandEnable handler of TDecoratedFrame attempts to
  103. provide the tooltip text by looking in two locations:
  104.  
  105. (a) First the window's menu is scanned for a menuitem with an id
  106. corresponding to that of the tool. If found, the menustring is
  107. provided.
  108.  
  109. (b) Next, TDecoratedFrame attempts to load a string resource
  110. with an id corresponding to that of the tool. If found, the
  111. string is scanned for a line-feed character. If successful,
  112. TDecoratedFrame provides the string following the line-feed as
  113. tooltip text.
  114.  
  115. NOTE: You should structure you hint text string using the
  116. following format:
  117.  <string to be displayed on statusbar>\n<tooltip hint text>
  118.  
  119. See the STRING TABLE in the .RC file of this example for more
  120. information.
  121.  
  122.  
  123.  
  124.